<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Using Programmatic Security with Web Applications - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level3"><a href="bncat.html">Overview of Web Application Security</a></p>
<p class="toc level3"><a href="gkbaa.html">Securing Web Applications</a></p>
<p class="toc level4"><a href="gkbaa.html#bncbk">Specifying Security Constraints</a></p>
<p class="toc level5"><a href="gkbaa.html#gjjcd">Specifying a Web Resource Collection</a></p>
<p class="toc level5"><a href="gkbaa.html#gjjcg">Specifying an Authorization Constraint</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbm">Specifying a Secure Connection</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbl">Specifying Separate Security Constraints for Various Resources</a></p>
<p class="toc level4 tocsp"><a href="gkbaa.html#gkbsa">Specifying Authentication Mechanisms</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbo">HTTP Basic Authentication</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbq">Form-Based Authentication</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbw">Digest Authentication</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbs">Client Authentication</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbt">Mutual Authentication</a></p>
<p class="toc level5"><a href="gkbaa.html#bncbn">Specifying an Authentication Mechanism in the Deployment Descriptor</a></p>
<p class="toc level4 tocsp"><a href="gkbaa.html#bncav">Declaring Security Roles</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Using Programmatic Security with Web Applications</a></p>
<p class="toc level4"><a href="#gircj">Authenticating Users Programmatically</a></p>
<p class="toc level4"><a href="#bncba">Checking Caller Identity Programmatically</a></p>
<p class="toc level4"><a href="#gjjlq">Example Code for Programmatic Security</a></p>
<p class="toc level4"><a href="#bncbb">Declaring and Linking Role References</a></p>
</div>
<p class="toc level3 tocsp"><a href="bncbx.html">Examples: Securing Web Applications</a></p>
<p class="toc level4"><a href="bncbx.html#gjjlk">To Set Up Your System for Running the Security Examples</a></p>
<p class="toc level4"><a href="bncbx.html#bncck">Example: Basic Authentication with a Servlet</a></p>
<p class="toc level5"><a href="bncbx.html#gjrmh">Specifying Security for Basic Authentication Using Annotations</a></p>
<p class="toc level5"><a href="bncbx.html#gjqys">To Build, Package, and Deploy the Servlet Basic Authentication Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bncbx.html#gjqzh">To Build, Package, and Deploy the Servlet Basic Authentication Example Using Ant</a></p>
<p class="toc level5"><a href="bncbx.html#gjqzf">To Run the Basic Authentication Servlet</a></p>
<p class="toc level4 tocsp"><a href="bncbx.html#bncby">Example: Form-Based Authentication with a JavaServer Faces Application</a></p>
<p class="toc level5"><a href="bncbx.html#bncca">Creating the Login Form and the Error Page</a></p>
<p class="toc level5"><a href="bncbx.html#bnccb">Specifying Security for the Form-Based Authentication Example</a></p>
<p class="toc level5"><a href="bncbx.html#gjrba">To Build, Package, and Deploy the Form-Based Authentication Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bncbx.html#gjraz">To Build, Package, and Deploy the Form-Based Authentication Example Using Ant</a></p>
<p class="toc level5"><a href="bncbx.html#gjral">To Run the Form-Based Authentication Example</a></p>
<p class="toc level2 tocsp"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="gkbaa.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bncbx.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="gjiie"></a><h2>Using Programmatic Security with Web Applications</h2>
<a name="indexterm-2084"></a><p>Programmatic security is used by security-aware applications when declarative security alone is not
sufficient to express the security model of the application.</p>



<a name="gircj"></a><h3>Authenticating Users Programmatically</h3>
<a name="indexterm-2085"></a><a name="indexterm-2086"></a><a name="indexterm-2087"></a><p>Servlet 3.0 specifies the following methods of the <tt>HttpServletRequest</tt> interface that enable
you to authenticate users for a web application programmatically:</p>


<ul><li><p><tt>authenticate</tt>, which allows an application to instigate authentication of the request caller by the container from within an unconstrained request context. A login dialog box displays and collects the user name and password for authentication purposes.</p>

</li>
<li><p><tt>login</tt>, which allows an application to collect username and password information as an alternative to specifying form-based authentication in an application deployment descriptor.</p>

</li>
<li><p><tt>logout</tt>, which allows an application to reset the caller identity of a request.</p>

</li></ul>
<p>The following example code shows how to use the <tt>login</tt> and <tt>logout</tt>
methods:</p>

<pre>package test;

import java.io.IOException;
import java.io.PrintWriter;
import java.math.BigDecimal;
import javax.ejb.EJB;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@WebServlet(name="TutorialServlet", urlPatterns={"/TutorialServlet"})
public class TutorialServlet extends HttpServlet {
    @EJB
    private ConverterBean converterBean;

    /**
     * Processes requests for both HTTP &lt;code>GET&lt;/code> 
     *    and &lt;code>POST&lt;/code> methods.
     * @param request servlet request
     * @param response servlet response
     * @throws ServletException if a servlet-specific error occurs
     * @throws IOException if an I/O error occurs
     */
    protected void processRequest(HttpServletRequest request, 
            HttpServletResponse response)
    throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        try {

            out.println("&lt;html>");
            out.println("&lt;head>");
            out.println("&lt;title>Servlet TutorialServlet&lt;/title>");
            out.println("&lt;/head>");
            out.println("&lt;body>");
            request.<b>login</b>("TutorialUser", "TutorialUser");
            BigDecimal result = 
                converterBean.dollarToYen(new BigDecimal("1.0"));
            out.println("&lt;h1>Servlet TutorialServlet result of dollarToYen= "
                + result + "&lt;/h1>");
            out.println("&lt;/body>");
            out.println("&lt;/html>");
        } catch (Exception e) {
            throw new ServletException(e);
        } finally {
            request.<b>logout</b>();
            out.close();
        }
    }
}</pre><p>The following example code shows how to use the <tt>authenticate</tt> method:</p>

<pre>package com.sam.test;

import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class TestServlet extends HttpServlet {

    protected void processRequest(HttpServletRequest request, 
            HttpServletResponse response)
            throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        try {
            request.<b>authenticate</b>(response);
            out.println("Authenticate Successful");
        } finally {
            out.close();
        }
    }</pre>

<a name="bncba"></a><h3>Checking Caller Identity Programmatically</h3>
<a name="indexterm-2088"></a><a name="indexterm-2089"></a><a name="indexterm-2090"></a><a name="indexterm-2091"></a><p>In general, security management should be enforced by the container in a manner
that is transparent to the web component. The security API described in this
section should be used only in the less frequent situations in which the
web component methods need to access the security context information.</p>

<p>Servlet 3.0 specifies the following methods that enable you to access security information
about the component&rsquo;s caller:</p>


<ul><li><p><tt>getRemoteUser</tt>, which determines the user name with which the client authenticated. The <tt>getRemoteUser</tt> method returns the name of the remote user (the caller) associated by the container with the request. If no user has been authenticated, this method returns <tt>null</tt>.</p>

</li>
<li><p><tt>isUserInRole</tt>, which determines whether a remote user is in a specific security role. If no user has been authenticated, this method returns <tt>false</tt>. This method expects a <tt>String</tt> user <tt>role-name</tt> parameter.</p>

<p>The <tt>security-role-ref</tt> element should be declared in the deployment descriptor with a <tt>role-name</tt> subelement containing the role name to be passed to the method. Using security role references is discussed in <a href="#bncbb">Declaring and Linking Role References</a>.</p>

</li>
<li><p><tt>getUserPrincipal</tt>, which determines the principal name of the current user and returns a <tt>java.security.Principal</tt> object. If no user has been authenticated, this method returns <tt>null</tt>. Calling the <tt>getName</tt> method on the <tt>Principal</tt> returned by <tt>getUserPrincipal</tt> returns the name of the remote user.</p>

</li></ul>
<p>Your application can make business-logic decisions based on the information obtained using these
APIs.</p>



<a name="gjjlq"></a><h3>Example Code for Programmatic Security</h3>
<p>The following code demonstrates the use of programmatic security for the purposes of
programmatic login. This servlet does the following:</p>


<ol><li><p>It displays information about the current user.</p>

</li>
<li><p>It prompts the user to log in.</p>

</li>
<li><p>It prints out the information again to demonstrate the effect of the <tt>login</tt> method.</p>

</li>
<li><p>It logs the user out.</p>

</li>
<li><p>It prints out the information again to demonstrate the effect of the <tt>logout</tt> method.</p>

</li></ol>
<pre>package enterprise.programmatic_login;

import java.io.*;
import java.net.*;
import javax.annotation.security.DeclareRoles;
import javax.servlet.*;
import javax.servlet.http.*;

@DeclareRoles("javaee6user")
public class LoginServlet extends HttpServlet {

    /** 
     * Processes requests for both HTTP GET and POST methods.
     * @param request servlet request
     * @param response servlet response
     */
    protected void processRequest(HttpServletRequest request, 
                 HttpServletResponse response)
            throws ServletException, IOException {
        response.setContentType("text/html;charset=UTF-8");
        PrintWriter out = response.getWriter();
        try {
            String userName = request.getParameter("txtUserName");
            String password = request.getParameter("txtPassword");
            
            out.println("Before Login" + "&lt;br>&lt;br>");
            out.println("IsUserInRole?.." 
                        + request.isUserInRole("javaee6user")+"&lt;br>");
            out.println("getRemoteUser?.." + request.getRemoteUser()+"&lt;br>");
            out.println("getUserPrincipal?.." 
                        + request.getUserPrincipal()+"&lt;br>");
            out.println("getAuthType?.." + request.getAuthType()+"&lt;br>&lt;br>");
            
            try {
                request.login(userName, password); 
            } catch(ServletException ex) {
                out.println("Login Failed with a ServletException.." 
                    + ex.getMessage());
                return;
            }
            out.println("After Login..."+"&lt;br>&lt;br>");
            out.println("IsUserInRole?.." 
                        + request.isUserInRole("javaee6user")+"&lt;br>");
            out.println("getRemoteUser?.." + request.getRemoteUser()+"&lt;br>");
            out.println("getUserPrincipal?.." 
                        + request.getUserPrincipal()+"&lt;br>");
            out.println("getAuthType?.." + request.getAuthType()+"&lt;br>&lt;br>");
            
            request.logout();
            out.println("After Logout..."+"&lt;br>&lt;br>");
            out.println("IsUserInRole?.." 
                        + request.isUserInRole("javaee6user")+"&lt;br>");
            out.println("getRemoteUser?.." + request.getRemoteUser()+"&lt;br>");
            out.println("getUserPrincipal?.."
                        + request.getUserPrincipal()+"&lt;br>");
            out.println("getAuthType?.." + request.getAuthType()+"&lt;br>");
        } finally {
            out.close();
        }
    }
    ...
}</pre>

<a name="bncbb"></a><h3>Declaring and Linking Role References</h3>
<a name="indexterm-2092"></a><a name="indexterm-2093"></a><a name="indexterm-2094"></a><p>A <b>security role reference</b> defines a mapping between the name of a role that is
called from a web component using <tt>isUserInRole(String role)</tt> and the name of a
security role that has been defined for the application. If no <tt>security-role-ref</tt> element
is declared in a deployment descriptor and the <tt>isUserInRole</tt> method is called, the container
defaults to checking the provided role name against the list of all security
roles defined for the web application. Using the default method instead of using
the <tt>security-role-ref</tt> element limits your flexibility to change role names in an application
without also recompiling the servlet making the call.</p>

<p>The <tt>security-role-ref</tt> element is used when an application uses the <tt>HttpServletRequest.isUserInRole(String role)</tt>. The value passed
to the <tt>isUserInRole</tt> method is a <tt>String</tt> representing the role name of
the user. The value of the <tt>role-name</tt> element must be the <tt>String</tt>
used as the parameter to the <tt>HttpServletRequest.isUserInRole(String role)</tt>. The <tt>role-link</tt> must contain the name of
one of the security roles defined in the <tt>security-role</tt> elements. The container uses
the mapping of <tt>security-role-ref</tt> to <tt>security-role</tt> when determining the return value of
the call.</p>

<p>For example, to map the security role reference <tt>cust</tt> to the security role
with role name <tt>bankCustomer</tt>, the syntax would be: </p>

<pre>&lt;servlet>
...
    &lt;security-role-ref>
        &lt;role-name>cust&lt;/role-name>
        &lt;role-link>bankCustomer&lt;/role-link>
    &lt;/security-role-ref>
...
&lt;/servlet></pre><p>If the servlet method is called by a user in the <tt>bankCustomer</tt>
security role, <tt>isUserInRole("cust")</tt> returns <tt>true</tt>. </p>

<p>The <tt>role-link</tt> element in the <tt>security-role-ref</tt> element must match a <tt>role-name</tt> defined in
the <tt>security-role</tt> element of the same <tt>web.xml</tt> deployment descriptor, as shown here:</p>

<pre>&lt;security-role>
    &lt;role-name>bankCustomer&lt;/role-name>
&lt;/security-role></pre><p>A security role reference, including the name defined by the reference, is scoped
to the component whose deployment descriptor contains the <tt>security-role-ref</tt> deployment descriptor element.</p>


         </div>
         <div class="navigation">
             <a href="gkbaa.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bncbx.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

